/**
 * Socket模块基础类型定义
 * 
 * @description
 * 提供Socket通信模块所需的核心类型定义：
 * - 消息包装接口
 * - 网络状态枚举
 * - 回调函数类型
 * - 常量配置类
 * 
 * @namespace Socket
 * @author wz
 * @date 2024.9.10
 * @version 1.0.0
 */

/**
 * 请求消息包装接口
 * 用于封装发送给服务器的消息数据
 */
export interface SocketReqWrap {
    /** 消息号，标识消息类型 */
    cmd: number;
    /** 消息体数据，可以是任意类型 */
    body: any;
}

/**
 * 响应消息包装接口
 * 继承自ReqWrap，用于封装服务器返回的响应数据
 */
export interface SocketRespWrap extends SocketReqWrap {
    /** 响应消息描述，通常包含操作结果说明 */
    msg: string;
    /** 响应状态码，0表示成功，非0表示各种错误状态 */
    code: number;
}

/**
 * 原始消息数据接口
 * 用于表示解析后的消息数据结构
 */
export interface SocketMsgData {
    /** 消息类型标识符 */
    msgType: number;
    /** 消息的二进制数据 */
    data: Uint8Array;
}

/**
 * 消息回调函数类型定义
 * 用于处理服务器响应消息的回调函数
 * 
 * @param resp 服务器响应的消息包装对象
 */
export type SocketMsgCallback = (resp: SocketReqWrap) => void;    /**
     * 网络连接状态枚举
     * 定义Socket连接的各种状态
     */
export enum SocketState {
    /**
     * 正在连接
     */
    CONNECTING,
    /**
     * 已连接
     */
    OPEN,
    /**
     * 正在关闭
     */
    CLOSING,
    /**
     * 已关闭
     */
    CLOSED,
}

/**
 * 网络断开原因枚举
 * 定义Socket连接断开的各种原因
 */
export enum SocketReason {
    /** 强制关闭，主动调用close方法关闭连接 */
    FORCE = 0,
    /** 正常关闭，服务器主动关闭或网络异常 */
    CLOSE = 1,
    /** 连接超时，在指定时间内未能建立连接 */
    TIMEOUT = 2,
    /** 心跳超时，心跳包发送后未收到服务器响应 */
    HEART = 3
}    /**
     * Socket网络配置常量类
     * 
     * @description
     * 定义Socket通信所需的各种常量配置：
     * - 连接认证配置
     * - 心跳机制配置  
     * - 消息协议配置
     * - 性能限制配置
     * 
     * 消息协议格式：
     * [消息头(4字节)] + [消息类型(4字节)] + [消息体(N字节)]
     * 消息头记录整个消息的长度（消息号+消息体的总长度）
     */
export class SocketConst {
    /* ======================== 连接认证配置 ======================== */

    /**
     * 是否开启权限验证
     * true: 连接建立后需要先进行身份验证
     * false: 连接建立后可直接发送业务消息
     */
    static readonly isOpenAuth: boolean = true;

    /**
     * Socket连接验证码
     * 用于客户端身份验证的密钥
     * 生产环境中应使用更安全的认证机制
     */
    static readonly authcode = "123456789";

    /* ======================== 心跳机制配置 ======================== */

    /**
     * 是否开启心跳检测
     * true: 启用心跳保活机制，防止连接被网络设备断开
     * false: 不发送心跳包，可能导致长时间无数据传输时连接被断开
     */
    static readonly isOpenHeart: boolean = true;

    /**
     * 心跳发送时间间隔（秒）
     * 客户端每隔指定秒数向服务器发送一次心跳包
     * 建议值：3-30秒，根据网络环境调整
     */
    static readonly heartSendInterval: number = 5;

    /**
     * 心跳响应超时时间（秒）
     * 发送心跳包后等待服务器响应的最大时间
     * 超过此时间未收到响应则认为连接异常
     */
    static readonly heartTimeout: number = 2;

    /* ======================== 消息协议配置 ======================== */

    /**
     * 消息头长度（字节数）
     * 用4个字节（32位）表示消息长度
     * 支持最大消息长度：2^32 - 1 字节 (约4GB)
     */
    static readonly MsgHeadSize = 4;

    /**
     * 消息类型长度（字节数）
     * 用4个字节（32位）表示消息类型
     * 支持消息类型范围：0 - 4,294,967,295
     */
    static readonly MsgTypeSize = 4;

    /* ======================== 性能限制配置 ======================== */

    /**
     * 单条WebSocket消息最大长度限制（字节）
     * 设置为10MB，考虑了不同平台的限制：
     * - 浏览器：通常限制16MB
     * - Node.js：通常限制16MB  
     * - Python：通常限制1MB
     * - 移动端：建议不超过10MB以避免内存问题
     */
    static readonly MaxMsgSize = 1024 * 1024 * 10;
}